---
title: 'Naming components and hierarchy'
sidebar:
  order: 7
  title: Naming components and hierarchy
---

<YouTubeCallout id="VPfjrhDlkVc" title="How to Name Stories and Components" />

Storybook provides a powerful way to organize your stories, giving you the necessary tools to categorize, search, and filter your stories based on your organization's needs and preferences.

## Structure and hierarchy

When organizing your Storybook, there are two methods of structuring your stories: **implicit** and **explicit**. The [implicit method](../configure/user-interface/sidebar-and-urls.mdx#csf-30-auto-titles) involves relying upon the physical location of your stories to position them in the sidebar, while the [explicit method](#naming-stories) involves utilizing the `title` parameter to place the story.

![Storybook sidebar hierarchy](../_assets/writing-stories/naming-hierarchy-sidebar-anatomy.png)

Based on how you structure your Storybook, you can see that the story hierarchy is made up of various parts:

* **Category**: The top-level grouping of stories and documentation pages generated by Storybook
* **Folder**: A mid-level organizational unit that groups components and stories in the sidebar, representing a feature or section of your application
* **Component**: A low-level organizational unit representing the component that the story is testing
* **Docs**: The automatically generated [documentation page](../writing-docs/autodocs.mdx) for the component
* **Story**: The individual story testing a specific component state

## Naming stories

When creating your stories, you can explicitly use the `title` parameter to define the story's position in the sidebar. It can also be used to [group](#grouping) related components together in an expandable interface to help with Storybook organization providing a more intuitive experience for your users. For example:

{/* prettier-ignore-start */}

<CodeSnippets path="button-story-default-export.md" />

{/* prettier-ignore-end */}

Yields this:

![Stories hierarchy without paths](../_assets/writing-stories/naming-hierarchy-no-path.png)

## Grouping

It is also possible to group related components in an expandable interface to help with Storybook organization. To do so, use the `/` as a separator:

{/* prettier-ignore-start */}

<CodeSnippets path="button-story-grouped.md" />

{/* prettier-ignore-end */}

{/* prettier-ignore-start */}

<CodeSnippets path="checkbox-story-grouped.md" />

{/* prettier-ignore-end */}

Yields this:

![Stories hierarchy with paths](../_assets/writing-stories/naming-hierarchy-with-path.png)

## Roots

By default, the top-level grouping will be displayed as “root” in the Storybook UI (i.e., the uppercased, non-expandable items). If you need, you can [configure Storybook](../configure/user-interface/sidebar-and-urls.mdx#roots) and disable this behavior. Useful if you need to provide a streamlined experience for your users; nevertheless, if you have a large Storybook composed of multiple component stories, we recommend naming your components according to the file hierarchy.

<If notRenderer="svelte">

  ## Single-story hoisting

  Single-story components (i.e., component stories without **siblings**) whose **display name** exactly matches the component's name (last part of `title`) are automatically hoisted up to replace their parent component in the UI. For example:

  {/* prettier-ignore-start */}

  <CodeSnippets path="button-story-hoisted.md" />

  {/* prettier-ignore-end */}

  ![Stories hierarchy with single story hoisting](../_assets/writing-stories/naming-hierarchy-single-story-hoisting.png)

  Because story exports are automatically "start cased" (`myStory` becomes `"My Story"`), your component name should match that. Alternatively, you can override the story name using `myStory.storyName = '...'` to match the component name.

</If>

## Sorting stories

Out of the box, Storybook sorts stories based on the order in which they are imported. However, you can customize this pattern to suit your needs and provide a more intuitive experience by adding `storySort` to the `options` parameter in your `preview.js` file.

{/* prettier-ignore-start */}

<CodeSnippets path="storybook-preview-sort-function.md" />

{/* prettier-ignore-end */}

<Callout variant="info">
  Asides from the unique story identifier, you can also use the `title`, `name`, and import path to sort your stories using the `storySort` function.
</Callout>

The `storySort` can also accept a configuration object.

{/* prettier-ignore-start */}

<CodeSnippets path="storybook-preview-empty-sort-object.md" />

{/* prettier-ignore-end */}

| Field            | Type    | Description                                              | Required | Default Value           | Example                   |
| ---------------- | ------- | -------------------------------------------------------- | -------- | ----------------------- | ------------------------- |
| **method**       | String  | Tells Storybook in which order the stories are displayed | No       | Storybook configuration | `'alphabetical'`          |
| **order**        | Array   | The stories to be shown, ordered by supplied name        | No       | Empty Array `[]`        | `['Intro', 'Components']` |
| **includeNames** | Boolean | Include story name in sort calculation                   | No       | `false`                 | `true`                    |
| **locales**      | String  | The locale required to be displayed                      | No       | System locale           | `en-US`                   |

To sort your stories alphabetically, set `method` to `'alphabetical'` and optionally set the `locales` string. To sort your stories using a custom list, use the `order` array; stories that don't match an item in the `order` list will appear after the items in the list.

The `order` array can accept a nested array to sort 2nd-level story kinds. For example:

{/* prettier-ignore-start */}

<CodeSnippets path="storybook-preview-with-ordered-pages.md" />

{/* prettier-ignore-end */}

Which would result in this story ordering:

1. `Intro` and then `Intro/*` stories
2. `Pages` story
3. `Pages/Home` and `Pages/Home/*` stories
4. `Pages/Login` and `Pages/Login/*` stories
5. `Pages/Admin` and `Pages/Admin/*` stories
6. `Pages/*` stories
7. `Components` and `Components/*` stories
8. All other stories

If you want specific categories to sort to the end of the list, you can insert a `*` into your `order` array to indicate where "all other stories" should go:

{/* prettier-ignore-start */}

<CodeSnippets path="storybook-preview-with-ordered-pages-and-wildcard.md" />

{/* prettier-ignore-end */}

In this example, the `WIP` category would be displayed at the end of the list.

Note that the `order` option is independent of the `method` option; stories are sorted first by the `order` array and then by either the `method: 'alphabetical'` or the default `configure()` import order.
